novatek: the mask ROM's fallback and UART download, so defib recovers a blank NT9856x - #225

• Model NA51089 recovery from invalid flash loaders, including source order, timeouts, and console
 output.
• Implement the mask ROM’s UART download commands so defib can boot a loader from blank flash.
• Add protocol tests and CI recovery runs for NT98562 and NT98566.

graph TD
  M["Machine options"] --> R["ROM recovery"] --> F{"Valid flash loader?"} -->|no| SD["SD probe"] --> ETH["Ethernet wait"] --> USB["USB wait"] --> UART["UART commands"] -->|validated| RUN["Loader jump"]
  F -->|yes| RUN
  R -->|UART strap| UART
  R -->|SD strap| SD
  R -->|Ethernet strap| ETH
  R -->|USB strap| USB
  UART -->|rejected or timed out| SD

Loading

The following are alternative approaches to this PR:

1. Execute a dumped silicon ROM

• ➕ Could reproduce recovery behavior without hand-modeling individual protocol quirks.
• ➖ Requires distributing or supplying a ROM image and integrating it with the existing emulated ROM services.

Recommendation: Keep the behavioral model: it works with the existing boot-ROM device and lets tests exercise unmodified defib without a proprietary ROM image. Treat the Ethernet stage’s lack of actual DHCP/TFTP traffic as an explicit scope limit for the follow-up.

Enhancement (4) +501 / -6

novatek.cWire recovery controls into NA51089 machine boot +66/-2

Wire recovery controls into NA51089 machine boot

• Adds rom-fallback and rom-fast machine properties and classifies flash versus recovery straps. Instantiates the boot-ROM device for eligible fallback boots even when flash has no loader, while preserving the existing stand-in path otherwise.

qemu/hw/arm/novatek.c

nvt-bootrom.cModel mask-ROM fallback and UART download behavior +407/-4

Model mask-ROM fallback and UART download behavior

• Adds loader validation, strap-selected recovery stages, console output, timers, and a parked CPU that resumes when a loader passes validation. Implements 16-byte UART commands, download storage, checksum and payload quirks, and draining of bytes received outside the UART stage.

qemu/hw/arm/nvt-bootrom.c

novatek.hDeclare machine-to-ROM recovery configuration +6/-0

Declare machine-to-ROM recovery configuration

• Exposes the fallback configuration and flash-strap classification functions used when wiring the Novatek boot-ROM device.

qemu/include/hw/arm/novatek.h

nvt-bootrom.hAdd boot-ROM recovery and UART state +22/-0

Add boot-ROM recovery and UART state

• Extends the device state with recovery options, stage timers, source tracking, and UART command and loader-transfer fields.

qemu/include/hw/arm/nvt-bootrom.h

Documentation (2) +55 / -4

CLAUDE.mdDocument the ROM recovery model in repository guidance +5/-1

Document the ROM recovery model in repository guidance

• Notes when NA51089 fallback runs, identifies the UART recovery path, and links to the recovery test and detailed documentation.

CLAUDE.md

novatek.mdDescribe recovery sources, UART commands, and defib usage +50/-3

Describe recovery sources, UART commands, and defib usage

• Documents strap-selected source order, console output, loader validation, UART protocol quirks, and shortened waits. Adds a blank-flash defib example and clarifies that Ethernet recovery does not yet send DHCP traffic.

docs/novatek.md

Other (3) +263 / -0

ci.ymlRun defib recovery in CI for two NT9856x machines +32/-0

Run defib recovery in CI for two NT9856x machines

• Adds a matrix job for NT98562 and NT98566 that installs defib, downloads the built QEMU binary, and runs both recovery paths.

.github/workflows/ci.yml

test-novatek-recovery.shExercise blank-flash recovery with unmodified defib +95/-0

Exercise blank-flash recovery with unmodified defib

• Starts QEMU with a blank flash for direct UART and NOR-fallback entry, runs defib burn, and verifies that the resulting U-Boot prompt answers a command. Supports SoC selection and retained logs.

qemu-boot/test-novatek-recovery.sh

test-novatek.pyTest UART command quirks and fallback console output +136/-0

Test UART command quirks and fallback console output

• Adds a socket-backed blank-flash fixture and checks command alignment, checksum responses, memory access, payload aliasing, loader execution, and the fallback’s console sequence.

qemu/tests/test-novatek.py

Description

rom_flash_loader_ok() checks the image checksum but not whether header word 1 matches the SRAM
destination. With a flash strap and fallback enabled, a checksum-valid image naming the wrong
destination skips recovery and enters the direct boot path, even though the fallback loader check
would reject it.

Description

The boot-novatek-recovery job installs OpenIPC/defib from its mutable default branch rather than a
reviewed commit, then relies on its burn interface and the exact message “U-Boot console ready.”
On push-to-master and pull-request runs, an upstream change or compromise can change the code
executed during installation and the recovery test, while an interface or wording change can fail
the job.

Description

nvt_rom_strap_is_flash counts only straps 0, 2, 3, 6, 8, 9 and 0xA as flash, but
rom_first_source in nvt-bootrom.c (and its comment, "the rest flash") sends every strap other than
0xC, 4, 1, 5 and 0xB to flash. So straps 7, 0xD, 0xE and 0xF switch the fallback on without being
asked, replacing the stand-in on a blank flash, yet the ROM then treats them as flash boots — which
contradicts the docs' "not a flash strap" rule.

Description

vmstate_nvt_bootrom saves only args and ret, omitting the fallback stage and retry count, UART
command and transfer progress, and both timers. A snapshot taken while the CPU is parked in WFI
during fallback or a UART download restores without the pending poll or timeout and without the
state needed to finish a partially received command.

Code

qemu/include/hw/arm/nvt-bootrom.h[R49-52]

+    QEMUTimer *timer;           /* the current stage's timeout */
+    QEMUTimer *poll;            /* the UART receive poll */
+    int source;                 /* the stage running, NVT_SRC_* */
+    int tries;

Evidence

The fallback keeps its stage, retry count, UART command and transfer progress in new struct fields
and uses two QEMUTimers for polling and timeouts. The registered device VMState was not extended
beyond args and ret, so it cannot restore the state that drives stage transitions or command
completion.

qemu/include/hw/arm/nvt-bootrom.h[40-59]
qemu/hw/arm/nvt-bootrom.c[970-979]
qemu/include/hw/arm/nvt-bootrom.h[49-59]
qemu/hw/arm/nvt-bootrom.c[728-745]
qemu/hw/arm/nvt-bootrom.c[776-801]
qemu/hw/arm/nvt-bootrom.c[974-984]
qemu/hw/arm/nvt-bootrom.c[1004-1011]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Active fallback stages and UART downloads lose their timers and progress across migration, potentially leaving a restored CPU parked in WFI with no pending wakeup.
## Fix Focus Areas
- qemu/include/hw/arm/nvt-bootrom.h[49-59]
- qemu/hw/arm/nvt-bootrom.c[970-984]
## Recommended Fix
Bump `version_id` and extend the device VMState with `VMSTATE_INT32` for `source`, `tries`, and `nchunk`; `VMSTATE_BOOL` for `storing` and `echo_due`; `VMSTATE_UINT8_ARRAY` for `chunk` and `wr_cdb`; `VMSTATE_UINT32` for `dest`, `size`, and `count`; and `VMSTATE_TIMER_PTR` for `timer` and `poll`. Test migration during a partially received command and during a stage timeout. Alternatively, mark the device unmigratable while `source` is not `NVT_SRC_DONE`.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

💡 Did you know, you can commit Qodo's fix in one click with committable suggestions (GitHub & GitLab)

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗